home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Format CD 52
/
Amiga Format AFCD52 (Issue 136, May 2000).iso
/
-serious-
/
programming
/
other
/
wla_020_3.0
/
wla_020_2.3
/
wla.txt
< prev
next >
Wrap
Text File
|
2000-02-28
|
25KB
|
926 lines
------------------------------------------------------------------------------
WLA GB-Z80 Macro Assembler v2.3 Copyright 1998-2000 by Ville Helin
------------------------------------------------------------------------------
1..... Introduction
2..... WLA History
3..... WLALINK History
4..... Assembler Directives
5..... Assembler Syntax
5.1.. Case Sensitivity
5.2.. Comments
5.3.. Labels
5.4.. Number Types
5.5.. Strings
5.6.. Supported GB-Z80 Commands
6..... Error Messages
7..... Supported Types
7.1.. ROM Size
7.2.. RAM Size
7.3.. Cartridge Type
8..... Bugs
9..... Files
9.1.. 'features_test.s'
9.2.. 'gb_hardware.i'
9.3.. 'cgb_hardware.i'
9.4.. 'nintendo_logo.i'
9.5.. 'pocket_voice.i'
10.... Temporary Files
11.... Compiling
11.1. Compiling ROM Images
11.2. Compiling Object Files
11.3. Compiling Library Files
12.... Linking
13.... Pocket Voice
14.... Author
15.... Thanks
16.... Future
17.... Support
18.... Legal Note
------------------------------------------------------------------------------
1... Introduction
------------------------------------------------------------------------------
Here is yet another macro assembler to help you to produce Game Boy software.
I wrote this because I had never written an assembler before and I really
needed a macro assembler which could read the GB-Z80 code I wrote. ;)
This is my ideal GB-Z80 macro assembler (not in final form, not yet). ;)
Tastes differ. Thus WLA!
I will not release WLA's source code, not now, as it is ugly, and would
put me into shame. ;) Any comments are gladly accepted. And if you produce
nice software with WLA, send me mail about it (or even the whole programme)!
;)
------------------------------------------------------------------------------
2... WLA History
------------------------------------------------------------------------------
v2.3 (23-Jan-2000) Added .SECTION, .ENDS.
Added "-l" -option for library file producing.
Fixed address calculations a little more.
WLA returns -1 when execution ended in error.
Local labels are now local to sections or object file.
Enhanced the documents.
v2.2 (16-Jan-2000) Added .DSW, .DW, .ENUM and .ENDE.
v2.1 (14-Jan-2000) Added $BE (Pocket Voice) to supported cartridge types.
Added "-v" -option for verbose information displaying.
Optimized pass 1.
Fixed possible errors in address calculations.
v2.0 (12-Jan-2000) Enhanced the documents.
Optimized internal pass 2 and directive including.
Fixed overflow check (in .ORG).
Added "-o" -option for object file producing.
Added linker executable "wlalink".
Added .INCDIR.
v1.9 (06-Jan-2000) Optimized .INCBIN, .INCLUDE and internal passes
1 and 2.
v1.8 (23-Dec-1999) Enhanced the documents.
Fixed overflow checker once again. Every bank gained one
byte more (total 16384).
v1.7 (04-Dec-1999) Enhanced the documents.
Added gb_hardware.i.
.INCBIN didn't free buffer memory.
Optimized .INCBIN.
.INCBIN now caches all the files.
Optimized internal passes 1 and 2.
Linux version is optimized for 486.
v1.6 (14-Nov-1999) Enhanced the documents.
Fixed nintendo_logo.i so it works on a real Game Boy.
Fixed complement check calculation to work.
Overflow checker thought GB ROM banks were 8KB each!
Fixed to 16KB. Ville no baka!
Added .REPT.
Added .ENDR.
v1.5 (10-Jun-1999) Enhanced the documents.
WLA does now one pass to the input data and
two passes to the internal data.
v1.4 (25-May-1999) Renamed nintendo_logo.s to nintendo_logo.i.
Fixed nintendo_logo.i Wzonka-Lad-compatible.
Fixed pass-texts, as WLA does actually one pass,
three of the old ones were made to the WLA's internal data.
Added one funky new optcode, "DEBUG", which will
translate to $ED (unused in GB-Z80). This one will
flash the power light when executed on Wzonka-Lad,
my Game Boy emulator. Use it only for debugging!
v1.3 (01-Jan-1999) Enhanced the documents.
WLA now shows the unused areas of the ROM file after
a successful compile in hexadecimal format.
Many WLA directives accepted non-pure values, not anymore.
Added .DSB.
.DB handles now strings as well.
v1.2 (21-Dec-1998) Enhanced the documents.
Added a list ("gb-z80.txt") of the supported GB-Z80 commands
to the archive.
Free strings don't break the compile loop anymore.
Added .INCBIN.
v1.1 (13-Dec-1998) Enhanced the documents.
Removed an unused function.
Number input now detects and discards numbers from
outside the word boundaries.
WLA now shows the unused areas of the ROM file after
a successful compile.
Added .IFNDEF.
Added .IFDEF.
Added .ELSE.
Added .ENDIF.
Added @@@ to .MACRO.
.DB accepted values from outside the byte boundaries.
v1.0 (12-Dec-1998) The first public release.
------------------------------------------------------------------------------
3... WLALINK History
------------------------------------------------------------------------------
v1.2 (23-Jan-2000) Added support for library files.
v1.1 (14-Jan-2000) Added support for Pocket Voice.
Added "-v" -option for verbose information displaying.
WLALINK now checks the object file formats.
v1.0 (12-Jan-2000) The first public release.
------------------------------------------------------------------------------
4... Assembler Directives
------------------------------------------------------------------------------
The directives are collected as they appear. Group 2 directives take place
as they are found. Group 1 directives are applied at the very end, after
all the code has been processed, where they overwrite the actual code.
Here are the supported directives (with examples) in WLA:
Group 1:
.NAME = "NAME OF THE ROM"
.ROMSIZE = 0
.RAMSIZE = 0
.EMPTYFILL = $C9
.CARTRIDGETYPE = 1
.LICENSEECODEOLD = $1A
.LICENSEECODENEW = "1A"
.COMPUTECHECKSUM
.COMPUTECOMPLEMENTCHECK
Group 2:
.INCDIR "/usr/programming/gb/include/"
.INCLUDE "cgb_hardware.i"
.INCBIN "sorority.bin"
.MACRO TEST
.ENDM
.BANK = 0
.ORG = $150
.DSB 256 $10
.DSW 128 20
.DB 100 $30 %1000 "HELLO WORLD!"
.DW 16000 10 255
.DEFINE IF $FF0F
.IFDEF IF
.IFNDEF IF
.ELSE
.ENDIF
.REPT 6
.ENDR
.ENUM $C000
.ENDE
.SECTION "Init"
.ENDS
Descriptions:
-------------------------
.NAME = "NAME OF THE ROM"
-------------------------
Fills the 16 bytes ranging from $134 to $143 with the provided string.
If the string is shorter than 16 bytes the remaining space is filled with $00.
This is not a compulsory directive.
------------
.ROMSIZE = 0
------------
Indicates the size of the ROM. This is a standard GB ROM size indicator value
found at $148 in a GB ROM, and there this one is put to also.
This is a compulsory directive.
------------
.RAMSIZE = 0
------------
Indicates the size of the RAM. This is a standard GB RAM size indicator value
found at $149 in a GB ROM, and there this one is put to also.
This is a compulsory directive.
----------------
.EMPTYFILL = $C9
----------------
This byte is used in filling the unused areas of the ROM file. EMPTYFILL
defaults to $00.
This is not a compulsory directive.
------------------
.CARTRIDGETYPE = 1
------------------
Indicates the type of the cartridge (mapper and so on). This is a standard
GB cartridge type indicator value found at $147 in a GB ROM, and there this
one is put to also.
This is not a compulsory directive.
----------------------
.LICENSEECODEOLD = $1A
----------------------
This is a standard old licensee code found at $14B in a GB ROM, and there this
one is put to also. .LICENSEECODEOLD cannot be defined with .LICENSEECODENEW.
This is not a compulsory directive.
-----------------------
.LICENSEECODENEW = "1A"
-----------------------
This is a standard new licensee code found at $144 and $145 in a GB ROM, and
there this one is put to also. .LICENSEECODENEW cannot be defined with
.LICENSEECODEOLD. $33 is inserted into $14B, as well.
This is not a compulsory directive.
----------------
.COMPUTECHECKSUM
----------------
When this directive is used WLA computes the ROM checksum found at $14E and
$14F in a GB ROM.
This is not a compulsory directive.
-----------------------
.COMPUTECOMPLEMENTCHECK
-----------------------
When this directive is used WLA computes the ROM complement check found at
$14D in a GB ROM.
This is not a compulsory directive, but very recommended. ;)
--------------------------------------
.INCDIR "/usr/programming/gb/include/"
--------------------------------------
Changes the current include root directory. Use this to specify main
directory for the following .INCLUDE and .INCBIN directives.
This is not a compulsory directive.
-------------------------
.INCLUDE "cgb_hardware.i"
-------------------------
Includes the specified file to the source file.
This is not a compulsory directive.
----------------------
.INCBIN "sorority.bin"
----------------------
Includes the specified data file into the source file. .INCBIN caches
all files into memory, so you can .INCBIN any data file millions of
times, but it is loaded only once.
This is not a compulsory directive.
-----------
.MACRO TEST
-----------
Begins a macro called 'TEST'. Macro text size is at max 1024 bytes.
You can use '@@@' inside a macro to eg. separate a label from the other
macro 'TEST' occurrences. Take a look at the supplied source code
'features_test.s' for more information. You can use a macro with '@@@' at
max 1000 times. '@@@' is converted to an integer ranging from 0 to 999 at
compile time.
This is not a compulsory directive.
-----
.ENDM
-----
Ends the macro.
This is not a compulsory directive, but when .MACRO is used this one is
required to terminate it.
---------
.BANK = 0
---------
Selects the ROM bank.
This is a compulsory directive.
-----------
.ORG = $150
-----------
Selects the starting address. The value supplied here is relative to the
ROM bank given with .BANK.
This is a compulsory directive.
------------
.DSB 256 $10
------------
Defines 256 bytes of $10.
This is not a compulsory directive.
-----------
.DSW 128 20
-----------
Defines 128 words (two bytes) of 20.
This is not a compulsory directive.
--------------------------------
.DB 100 $30 %1000 "HELLO WORLD!"
--------------------------------
Defines bytes.
This is not a compulsory directive.
----------------
.DW 16000 10 255
----------------
Defines words (two bytes each). .DW takes only numbers and
characters as input, not strings.
This is not a compulsory directive.
----------------
.DEFINE IF $FF0F
----------------
Assigns a number to a string. This is all it can do, nothing else.
Defined strings can only be found amid the GB-Z80 code.
This is not a compulsory directive.
---------
.IFDEF IF
---------
If "IF" is defined, then the following piece of code is acknoledged
until .ENDIF occurs in the text, unless it is skipped.
This is not a compulsory directive.
----------
.IFNDEF IF
----------
If "IF" is not defined, then the following piece of code is acknoledged
until .ENDIF occurs in the text, unless it is skipped.
This is not a compulsory directive.
-----
.ELSE
-----
If the previous .IFDEF or .IFNDEF failed then the following text until
.ENDIF is acknoledged.
This is not a compulsory directive.
------
.ENDIF
------
This terminates any .IFDEF or .IFNDEF directive.
This is not a compulsory directive, but if you use .IFDEF or .IFNDEF then
you need also to apply this.
-------
.REPT 6
-------
Repeats the text enclosed between ".REPT x" and ".ENDR" x times (6 in
this example). Repetition text size is at max 1024 bytes.
This is not a compulsory directive.
-----
.ENDR
-----
Ends the repetition.
This is not a compulsory directive, but when .REPT is used this one is
required to terminate it.
-----------
.ENUM $C000
-----------
Starts enumeration from $C000. Very useful for defining variables.
Here's an example:
...
.ENUM $A000
_scroll_x DB
_scroll_y DB
player_x DW
player_y DW
map_01 DS 1024
map_02 DS 2048
.ENDE
...
Previous example transforms into following definitions:
.DEFINE _scroll_x $A000
.DEFINE _scroll_y $A001
.DEFINE player_x $A002
.DEFINE player_y $A004
.DEFINE map_01 $A006
.DEFINE map_02 $A406
This is not a compulsory directive.
-----
.ENDE
-----
Ends the enumeration.
This is not a compulsory directive, but when .ENUM is used this one is
required to terminate it.
---------------
.SECTION "Init"
---------------
Begins a section called "Init". Before a section can be declared, .BANK
and .ORG must be used. .BANK tells the bank number where this section
will be later relocated into. .ORG tells the offset for the relocation
from the beginning of .BANK.
Here's an example:
...
.BANK 0
.ORG $150
.SECTION "Init"
DI
LD SP, $FFFE
SUB A
LD ($FF00+R_IE), A
.ENDS
...
This tells WLA that a section called "Init" must be located somewhere in
bank 0, but not $0-$14F.
This is not a compulsory directive.
-----
.ENDS
-----
Ends the section.
This is not a compulsory directive, but when .SECTION is used this one is
required to terminate it.
------------------------------------------------------------------------------
5... Assembler Syntax
------------------------------------------------------------------------------
5.1. Case Sensitivity
WLA is case sensitive, so be careful. All the directives must be in
uppercase.
5.2. Comments
Comments begin with ';' and end along with the line.
5.3. Labels
Labels are ordinary strings that end to ':'. Labels starting with "_"
are considered as local labels and do not show outside sections where
they were defined, or outside object files, if they were not defined
inside a section.
5.4. Number Types
You can't use arithmetic or logic expressions, all values must be precomputed.
1000 - decimal.
$100 - hexadecimal.
%100 - binary.
'x' - character.
5.5. Strings
Strings begin and end to '"'. Note that no 0 is inserted to indicate the
termination of the string like in eg. C. You'll have to do it yourself.
5.6. Supported GB-Z80 commands
Check out the file "z80.txt" coming in this archive.
Additionally there is a command called "DEBUG" which will translate to
$ED. This one is not used in real GB-Z80, but my Game Boy emulator,
Wzonka-Lad, will invert the power light mode when $ED is executed.
Don't use DEBUG if you are going to use your code elsewhere!
------------------------------------------------------------------------------
6... Error Messages
------------------------------------------------------------------------------
There are quite a few of them in WLA, but most of them are not as informative
as I would like them to be. This will be fixed in the future. Mean while, be
careful. ;)
------------------------------------------------------------------------------
7... Supported Types
------------------------------------------------------------------------------
7.1. ROM Size
$0 - 256Kbit = 32KByte = 2 banks
$1 - 512Kbit = 64KByte = 4 banks
$2 - 1Mbit = 128KByte = 8 banks
$3 - 2Mbit = 256KByte = 16 banks
$4 - 4Mbit = 512KByte = 32 banks
$5 - 8Mbit = 1MByte = 64 banks
$6 - 16Mbit = 2MByte = 128 banks
$52 - 9Mbit = 1.1MByte = 72 banks
$53 - 10Mbit = 1.2MByte = 80 banks
$54 - 12Mbit = 1.5MByte = 96 banks
7.2. RAM Size
$0 - None
$1 - 16kbit = 2kByte = 1 bank
$2 - 64kbit = 8kByte = 1 bank
$3 - 256kbit = 32kByte = 4 banks
$4 - 1Mbit = 128kByte = 16 banks
7.3. Cartridge Type
It's up to the user to check that the cartridge type is valid and
can be used combined with the supplied ROM and RAM sizes.
Here's a list of what the value can be:
$0 - ROM ONLY
$1 - ROM+MBC1
$2 - ROM+MBC1+RAM
$3 - ROM+MBC1+RAM+BATT
$5 - ROM+MBC
$6 - ROM+MBC2+BATTERY
$8 - ROM+RAM
$9 - ROM+RAM+BATTERY
$B - ROM+MMM01
$C - ROM+MMM01+SRAM
$D - ROM+MMM01+SRAM+BATT
$F - ROM+MBC3+TIMER+BATT
$10 - ROM+MBC3+TIMER+RAM+BATT
$11 - ROM+MBC3
$12 - ROM+MBC3+RAM
$13 - ROM+MBC3+RAM+BATT
$19 - ROM+MBC5
$1A - ROM+MBC5+RAM
$1B - ROM+MBC5+RAM+BATT
$1C - ROM+MBC5+RUMBLE
$1D - ROM+MBC5+RUMBLE+SRAM
$1E - ROM+MBC5+RUMBLE+SRAM+BATT
$1F - Pocket Camera
$BE - Pocket Voice
$FD - Bandai TAMA5
$FE - Hudson HuC-3
$FF - Hudson HuC-1
------------------------------------------------------------------------------
8... Bugs
------------------------------------------------------------------------------
If you find bugs, please let me know asap. Anything, small or big, send
me mail!
------------------------------------------------------------------------------
9... Files
------------------------------------------------------------------------------
9.1. 'features_test.s'
'features_test.s' shows how to use most of the WLA's directives and a
little of the GB-Z80 syntax itself.
The program it describes is supposed to change the background color, so it
doesn't do really anything fantastic. ;)
9.2. 'gb_hardware.i'
'gb_hardware.i' has all the Game Boy hardware register names. Names are
the same as found in numerous Game Boy hardware documentations.
9.3. 'cgb_hardware.i'
'cgb_hardware.i' has all the Color Game Boy hardware register names. Names
are the same as found in numerous Color Game Boy hardware documentations.
9.4. 'nintendo_logo.i'
Include this file to your projects if you want to run the code on a real
Game Boy. Required data for Nintendo Character Area.
9.5. 'pocket_voice.i'
Pocket Voice register and command definitions. Based on Bung's Pocket Voice
information.
------------------------------------------------------------------------------
10.. Temporary Files
------------------------------------------------------------------------------
Note that WLA will generate two temporary files while it works. Make sure
the directories where the temporary files are generated to exist.
On Amiga machines these files are placed in T: and are called
"gba_a.tmp" and "gba_b.tmp".
On Linux x86 systems these files are placed in /tmp/ and are called
".gba_a.tmp" and ".gba_b.tmp".
On MSDOS x86 machines these files are placed in C:\TEMP\ and are
called "GBA_A.TMP" and "GBA_B.TMP".
So remember not to use more than one WLA process at a time. I will
be honoured to fix this, but it requires a request from a WLA Power
User. ;)
When WLA finishes its work these two files are deleted as they serve
of no further use.
------------------------------------------------------------------------------
11.. Compiling
------------------------------------------------------------------------------
11.1. Compiling ROM images
To compile a ROM image from an asm file use the following:
"wla [-v] <ASM FILE> <OUTPUT FILE>"
One asm file, one ROM image. Simple, but not very flexible. Compile object
files and link them together in the case of a bigger project.
If "-v" is used, WLA displays information about ROM file after a
succesful compile.
11.2. Compiling Object Files
Version 2.0 of WLA introduced object files. To compile an object file use:
"wla [-v] <ASM FILE> -o <OUTPUT FILE>"
These object files can be linked together (or with library files) later
with "wlalink".
Name object files so that they can be recognized as object files. Normal
suffices are ".o" and ".obj".
With object files you can reduce the amount of compiling when editing
small parts of the program. Note also the possibility of using local
labels (starting with "_").
Note! When you compile objects, group 1 directives are saved for linking
time, when they are all compared and if they differ, an error message is
shown. It is advisable to use something like an include file to hold all
the group 1 directives for that particular project and include it to every
object file.
If you are interested in the WLA object file format, take a look at the
file "object_format.txt" which is included in the release archive.
If "-v" is used, WLA displays information about the object file after a
succesful compile.
11.3. Compiling Library Files
Version 2.3 of WLA introduced library files. To compile a library file use:
"wla [-v] <ASM FILE> -l <OUTPUT FILE>"
Name object files so that they can be recognized as library files. Normal
suffice is ".lib".
With library files you can reduce the amount of compiling. Library files
are meant to hold general functions that can be used in different projects.
Note also the possibility of using local labels (starting with "_").
If you are interested in the WLA library file format, take a look at the
file "wla_file_formats.txt" which is included in the release archive.
If "-v" is used, WLA displays information about the library file after a
succesful compile.
------------------------------------------------------------------------------
12.. Linking
------------------------------------------------------------------------------
After you have produced one or more object files and perhaps some library
files, you might want to link them together to produce a ROM image. "wlalink"
is the program you use for that. Here's how you use it:
"wlalink [-v] <OBJ1/LIB1> <OBJ2/LIB2> <OBJ3/LIB3> ... -o <OUTPUT FILE>"
Make sure all object files have same resolution (same ROM name, same ROM
size...), otherwise WLALINK will fail. And make sure you don't try to insert
libraries into banks that don't exist.
If "-v" is used, WLALINK displays information about ROM file after a
succesful linking.
------------------------------------------------------------------------------
13.. Pocket Voice
------------------------------------------------------------------------------
Pocket Voice uses its own MBC. You can enable Pocket Voice mode by selecting
Pocket Voice cartridge type ($BE). In PV mode bank 0 is 24KB and the rest
are 8KB. Note that WLA assumes that ROM offset is all the time 0.
If you use something else as the offset, make sure to compute the jumps by
hand as WLA cannot do that.
------------------------------------------------------------------------------
14.. Author
------------------------------------------------------------------------------
Ville Helin, the author of Wzonka-Lad, a Game Boy emulator for the Amiga
machines. I have 22 years behind me, many more to travel through. I study
information technology at the Helsinki University of Technology
(http://www.hut.fi). I like Game Boy (goes without saying), anime soap operas,
Japanese culture and Kung-Fu.
email: vhelin@cc.hut.fi
hpage: http://www.hut.fi/~vhelin
------------------------------------------------------------------------------
15.. Thanks
------------------------------------------------------------------------------
Thanks to Madonna MkII (Matra Computer Corp.) and Gaelan Griffin
for reporting bugs in WLA. I wouldn't mind if more people used WLA. ;)
Thanks to Mark Knox for helping me with the MSDOS port!
------------------------------------------------------------------------------
16.. Future
------------------------------------------------------------------------------
Future enhancements (if I get really inspired):
- Proper error messages with line numbers.
- Other optimizations, bug fixes and enhancements.
------------------------------------------------------------------------------
17.. Support
------------------------------------------------------------------------------
The currently supported systems are MSDOS/x86, AmigaOS/680x0 and Linux/x86.
If you'd like to see WLA for other platforms/configurations, send me mail
and we'll see what I can do.
------------------------------------------------------------------------------
18.. Legal Note
------------------------------------------------------------------------------
WLA GB-Z80 Macro Assembler Copyright 1998-2000 Ville Helin
I take no responsibility what WLA does on your machine. Remember
that when using WLA you do it at your own risk.
WLA is freeware as long as it is used to produce non-commercial software.
WLA cannot be used in any commercial project without my permission.
If and when WLA is used in a commercial project, I want something as
well, like the finished product. ;) Or credits would be nice. ;)
Something, so I know there are people using WLA.
WLA may not be put on any CD DISC or HD DISK or any other form of media
unless I myself grant the premission.
If I am not contacted before WLA is used in a process that involves money,
then may the seven drunken Gods strike such a foul business down! If the
Gods won't do me a favor, I'll ask Monkey King and come and do my Kung-Fu.
Game Boy and Game Boy Color are copyrighted by Nintendo.